home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / d / devpak / devpakv3.01kickstartv1.3b.dms / devpakv3.01kickstartv1.3b.adf / arp / prodocs / FileRequest < prev    next >
Text File  |  1991-11-20  |  6KB  |  199 lines
  1.  
  2.  
  3.  
  4.      FileRequest(33.4)      ARP Programmers Manual     FileRequest(33.4)
  5.  
  6.  
  7.  
  8.      NAME
  9.       FileRequest -- Get filename from user
  10.  
  11.      SYNOPSIS
  12.       file = FileRequest( FileRequester )
  13.        D0                 A0
  14.  
  15.      FUNCTION
  16.       This function    is an implementation of    the famous Heath
  17.       FileRequester.  It displays a    list of    files and directories
  18.       in a Intuition style filerequester, and returns the users
  19.       selection to you.  Additions to this function    in version
  20.       33.4 of the library allow you    much more flexibility and
  21.       control over the filerequester.  There have been a few
  22.       changes to the FileRequester structure, but these are
  23.       completely compatible    with the old struct, old code will
  24.       still    work, as long as the cautions regarding    the old
  25.       fr_Flags variable was    followed. (It must have    been
  26.       initialized to zero).
  27.  
  28.      INPUTS
  29.       FileRequester    -- A pointer to    an initialized FileRequester
  30.           structure.  The fr_FuncFlags variable    controls what
  31.           the user function pointed to by fr_Function receives
  32.           from FileRequest(). You may set more than one    task
  33.           for your function to perform,    FileRequest() passes
  34.           you a    copy of    the flag (note,    this is    the actual
  35.           flag value, not the bit number) which    caused the
  36.           function call, so you    will know what action to take.
  37.           You are also passed an object, which will vary
  38.           according to the flag    that caused the    function call.
  39.           Some of these    functions require you to return    a
  40.           value    to FileRequest,    this value should be returned
  41.           in D0.
  42.  
  43.       FileRequest()    places the arguments on    the stack in an    order
  44.       that allows the current generation of    Amiga 'C' compilers to
  45.       access them without a    low level language binding function.
  46.       All you need to do to    access the parameters from 'C' is to
  47.       declare the function as:
  48.  
  49.            fr_Function(mask, object)
  50.            LONGBITS    mask;
  51.            CPTR object;
  52.  
  53.  
  54.       To allow other languages access to this feature, and to
  55.       insure compatibility with future generations of C compilers
  56.       that may use a different stack frame,    the arguments are also
  57.       passed in registers D0 (for the mask)    and A0 (for the
  58.       object). Register A4 is guaranteed to    be the same as when
  59.       you called FileRequest(), which makes    it unnecessary to call
  60.  
  61.  
  62.  
  63.      Page 1                         (printed 2/22/88)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      FileRequest(33.4)      ARP Programmers Manual     FileRequest(33.4)
  71.  
  72.  
  73.  
  74.       geta4() type functions. It is    NOT guaranteed that A6 will
  75.       contain ArpBase.
  76.  
  77.       fr_Function may freely use registers d0-d1/a0-a1, you    may
  78.       also alter A4, if your compiler does not require it. All
  79.       other    registers must be preserved, including A6.
  80.  
  81.       FRB_DoWildFunc: You get a pointer to a FileInfoBlock.     If
  82.               you want this    file to    be added to the    file
  83.               requester display, return ZERO. Non zero
  84.               returns will prevent this name from being
  85.               displayed.
  86.  
  87.       FRB_DoMsgFunc:  Ordinarily if    FileRequest() receives an
  88.               IntuiMessage that does not apply to the
  89.               FileRequest()    gadgets    and windows, it    will
  90.               send the message back    to Intuition without
  91.               doing    anything else to it. This can occur if
  92.               FileRequest was passed a fr_Window pointer
  93.               and created a    shared IDCMP on    that windows
  94.               ports    (see FDB_NewIDCMP).
  95.  
  96.               If you want to get your hands    on these
  97.               messages, set    this bit in fr_FuncFlags, and
  98.               you will be passed a pointer to the
  99.               IntuiMessage that FileRequest() didn't
  100.               recognize. Note that it now becomes your
  101.               responsibility to return it to Intuition.
  102.               Returns from this function are ignored.
  103.  
  104.       FRB_NewWindFunc:
  105.               You get a pointer to the NewWindow structure
  106.               that FileRequest() is    about to open for the
  107.               file requester activities.  You may modify
  108.               it as    you require. It    is intended for
  109.               adjusting the    window position    of the
  110.               filerequester    and/or its size    which must be
  111.               legal    for the    requested screen.
  112.               FileRequest()    ignores    any return value from
  113.               this function.
  114.  
  115.       FRB_AddGadFunc: You get a pointer to the file    requester
  116.               window after FileRequest() has added all of
  117.               its standard gadgets,    but before they    are
  118.               actually drawn. You may add/remove your own
  119.               custom gadgets at this point.     FileRequest()
  120.               ignores any return value from    this function.
  121.  
  122.       FRB_GEventFunc: User is doing    something with a gadget    which
  123.               is unknown to    FileRequest().    You are    passed
  124.               the gadgetID of the gadget which caused the
  125.               event.  FileRequest()    reserves all gadget
  126.  
  127.  
  128.  
  129.      Page 2                         (printed 2/22/88)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      FileRequest(33.4)      ARP Programmers Manual     FileRequest(33.4)
  137.  
  138.  
  139.  
  140.               ID's greater than FR_FIRST_GADGET for    it's
  141.               own use.  (This has been made    sufficiently
  142.               large    so that    it will    not cause problems in
  143.               practice.)
  144.  
  145.               If you return    ZERO, the FileRequest()    will
  146.               continue, otherwise, it will exit. The exit
  147.               status from FileRequest() is undefined if
  148.               this occurs.
  149.  
  150.       FRB_ListFunc:      Is not implemented yet.
  151.  
  152.       The following    control    bits do    not cause a function to    be
  153.       called if set:
  154.  
  155.       FRB_DoColor:      This controls    the background color, you get
  156.               one of two choices, with or without the
  157.               DoColor bit set.  This is useful to
  158.               emphasize two    different uses of the
  159.               FileRequester    in the same program, for
  160.               example, Loading and saving files might use
  161.               different colored file requester backgrounds
  162.               to emphasize the difference.
  163.  
  164.       FRB_NewIDCMP:      This is used only if you have    specified a
  165.               value    for fr_Window.    Ordinarily,
  166.               FileRequest()    will create a shared IDCMP
  167.               using    the already opened IDCMP ports of your
  168.               window, since    this requires much less
  169.               overhead.  If    you do not wish    this to    occur,
  170.               you may set this bit,    which will cause the
  171.               FileRequest()    function to create its own
  172.               IDCMP    ports.
  173.  
  174.      RESULT
  175.       file -- pointer to the File buffer in    your FileRequest
  176.           structure, if    user selected OK.  If user selected
  177.           CANCEL, the return value will    be NULL.  Note that
  178.           you may have to do some further processing on    the
  179.           return values    of the fr_DIR and fr_File to determine
  180.           what the user    actually wanted.
  181.  
  182.      BUGS
  183.       None known.
  184.  
  185.      AUTHOR
  186.       CDH
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.      Page 3                         (printed 2/22/88)
  196.  
  197.  
  198.  
  199.